Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add ability to report the document layout in Microsoft Word #17324

Open
wants to merge 13 commits into
base: master
Choose a base branch
from

Conversation

nvdaes
Copy link
Contributor

@nvdaes nvdaes commented Oct 24, 2024

Link to issue number:

Fixes issue #15088

Summary of the issue:

Knowing the document layout in Microsoft Word may be important, for example, to figure out why a table is not read properly when navigating with NVDA, and in other situations.

Description of user facing changes

When using the report title command in Microsoft Word, if the document layout can be determined, it Will be added to the title.
When Microsoft Word is active, in the input gestures dialog, the description of this command will be presented indicating that it works in Word, in contrast to the report title command of global commands.

Description of development approach

In the WinWord app module, a script has been created, using api.getStatusBar() to search for the status bar. If it can be found, and one of the bar status children has the PRESSED state, its name Will be added to the title, assuming that it correspond to the document layout.

Testing strategy:

Tested manually, in Word documents, with the ribbon active and inactive, and with a dialog opened to check that the title without the document layout is reported when the status bar is not found.

Known issues with pull request:

None.

Code Review Checklist:

  • Documentation:
    • Change log entry
    • User Documentation
    • Developer / Technical Documentation
    • Context sensitive help for GUI changes
  • Testing:
    • Unit tests
    • System (end to end) tests
    • Manual testing
  • UX of all users considered:
    • Speech
    • Braille
    • Low Vision
    • Different web browsers
    • Localization in other languages / culture than English
  • API is compatible with existing add-ons.
  • Security precautions taken.

@coderabbitai summary

@AppVeyorBot
Copy link

  • FAIL: Translation comments check. Translation comments missing or unexpectedly included. See build log for more information.
  • PASS: License check.
  • PASS: Unit tests.
  • PASS: Lint check.
  • PASS: System tests (tags: installer NVDA).
  • Build (for testing PR): https://ci.appveyor.com/api/buildjobs/yj03ojc4b6wubepw/artifacts/output/l10nUtil.exe nvda_snapshot_pr17324-34415,c51766cc.exe
  • CI timing (mins):
    INIT 0.0,
    INSTALL_START 1.5,
    INSTALL_END 1.0,
    BUILD_START 0.0,
    BUILD_END 26.5,
    TESTSETUP_START 0.0,
    TESTSETUP_END 0.4,
    TEST_START 0.0,
    TEST_END 18.9,
    FINISH_END 0.1

See test results for failed build of commit c51766ccdb

@codeofdusk
Copy link
Contributor

codeofdusk commented Oct 25, 2024

I really don't think this should be in the title bar (it isn't visually, right?). Perhaps it could be assigned to a separate script?

@CyrilleB79
Copy link
Collaborator

Hi Noelia.

Thanks for addressing this issue. It will be very useful.

This approach with the status bar is not the best design choice IMO. Indeed, the view ribbon allow you to select outline or draft mode but there are no corresponding buttons, at least by default, in the status bar. Also, are we sure that the status bar cannot contain any other pressed button?

As suggested in #15088 (comment), I'd rather opt for the Word Object Model approach. Using the macro recorder and playing with the buttons in the view ribbon, you can find the relevant objects/properties/methods; then you can complete your information by googling the corresponding MSDN page (e.g. "VBA word view").

Also, rather than duplicating the NVDA+T script, I'd keep one single script. As for the processing done to read the status bar text (see api.getStatusBar), I'd create a function allowing to get the title in the general case or delegating this task to Word's appModule when in Word. The advantages of a single script are that:

  • the processing done with the text (e.g. spelll if two presses, etc.) remains factorized; so if we change what to do on triple press in the future, we will have to change it only at one place.
  • if someone change the script's gesture NVDA+t to NVDA+shift+t, it will be changed in all context at once. Keeping two separated scripts, people may not understand easily that they have to change the gesture in Word and out of Word.

To be complete, the drawback of having one single script is that you cannot use a separate description in Word.

@CyrilleB79
Copy link
Collaborator

Re @codeofdusk feedback:
It's true that the title bar does not show this information. Though, a dedicated script is not a better solution IMO.
If we want this feature to be useful, the information should:

  • either be reported along with a frequently used script (current implementation)
  • or reported upon a specific event, e.g. when the application gets the focus

@codeofdusk
Copy link
Contributor

What about including it in the name property of the document's NVDAObject?

@CyrilleB79
Copy link
Collaborator

What about including it in the name property of the document's NVDAObject?

Yes, that seems an interesting option. It would be reported when the document gets focused or when calling NVDA+tab.
It's worth noting that the name seems to be "Document Microsoft Word". We may replace it by "Document {viewMode}". No need to keep the "Microsoft Word" information; I should already know that I am in Word.

@nvdaes
Copy link
Contributor Author

nvdaes commented Oct 25, 2024

For me, adding this to the document name is a good option.
Though, according to #15088, in JAWS this seems to be reported in the title.
I think that this should be reported on demand when the user wants, not just when an event is fired.
Anyway, note that if we report this in the document name, when the ribbon is active it won't be availab.e.
My first approach was to include the script just in the document class, and then I moved it to the app module so that it's available from the ribbon too.
I'll wait for more feedback, or I can mark this as ready for review to see opinions from NV Access too.

@nvdaes
Copy link
Contributor Author

nvdaes commented Oct 25, 2024

Exploring Microsoft Word, pragmatically, I think that including this in the title may be more useful. For example, if we want to change the layout from the ribbon, we may press NVDA+tab to remember the focused button, and we can have the current layout in the title.

@nvdaes
Copy link
Contributor Author

nvdaes commented Oct 25, 2024

I'll mark this as ready for review, and feedback is welcome.

@nvdaes nvdaes marked this pull request as ready for review October 25, 2024 08:16
@nvdaes nvdaes requested a review from a team as a code owner October 25, 2024 08:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants